package cn.iocoder.yudao.module.system.service.userbehavior;

import cn.iocoder.yudao.framework.common.pojo.PageResult;
import cn.iocoder.yudao.module.system.dal.dataobject.userbehavior.UserBehaviorDetailDO;
import cn.iocoder.yudao.module.system.dal.dataobject.userbehavior.UserBehaviorStatsDO;
import cn.iocoder.yudao.module.system.dal.dataobject.userbehavior.UserFeaturePathDO;

import java.math.BigDecimal;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.util.List;
import java.util.Map;

/**
 * 用户行为统计 Service 接口
 *
 * @author 系统开发团队
 */
public interface UserBehaviorStatsService {

    // ========== 行为统计数据计算 ==========

    /**
     * 计算用户行为统计数据
     *
     * @param statDate 统计日期
     * @return 是否计算成功
     */
    boolean calculateUserBehaviorStats(LocalDate statDate);

    /**
     * 批量计算用户行为统计数据
     *
     * @param startDate 开始日期
     * @param endDate   结束日期
     * @return 是否计算成功
     */
    boolean batchCalculateUserBehaviorStats(LocalDate startDate, LocalDate endDate);

    /**
     * 重新计算用户行为统计数据
     *
     * @param statDate 统计日期
     * @return 是否计算成功
     */
    boolean recalculateUserBehaviorStats(LocalDate statDate);

    /**
     * 计算日行为统计
     *
     * @param statDate 统计日期
     * @return 行为统计数据
     */
    UserBehaviorStatsDO calculateDailyBehaviorStats(LocalDate statDate);

    /**
     * 计算周行为统计
     *
     * @param statDate 统计日期（周末日期）
     * @return 行为统计数据
     */
    UserBehaviorStatsDO calculateWeeklyBehaviorStats(LocalDate statDate);

    /**
     * 计算月行为统计
     *
     * @param statDate 统计日期（月末日期）
     * @return 行为统计数据
     */
    UserBehaviorStatsDO calculateMonthlyBehaviorStats(LocalDate statDate);

    // ========== 行为统计数据查询 ==========

    /**
     * 分页查询用户行为统计
     *
     * @param startDate          开始日期
     * @param endDate            结束日期
     * @param statType           统计类型
     * @param calculationStatus  计算状态
     * @param pageNo             页码
     * @param pageSize           页大小
     * @return 分页结果
     */
    PageResult<UserBehaviorStatsDO> getUserBehaviorStatsPage(LocalDate startDate, LocalDate endDate,
                                                              Integer statType, Integer calculationStatus,
                                                              int pageNo, int pageSize);

    /**
     * 获取用户行为统计概览
     *
     * @param startDate 开始日期
     * @param endDate   结束日期
     * @return 概览数据
     */
    Map<String, Object> getUserBehaviorStatsOverview(LocalDate startDate, LocalDate endDate);

    /**
     * 获取用户行为趋势
     *
     * @param startDate 开始日期
     * @param endDate   结束日期
     * @param statType  统计类型
     * @return 趋势数据
     */
    List<UserBehaviorStatsDO> getUserBehaviorTrend(LocalDate startDate, LocalDate endDate, Integer statType);

    /**
     * 获取用户行为统计详情
     *
     * @param statDate 统计日期
     * @param statType 统计类型
     * @return 统计详情
     */
    UserBehaviorStatsDO getUserBehaviorStatsDetail(LocalDate statDate, Integer statType);

    /**
     * 获取最新的用户行为统计
     *
     * @param statType 统计类型
     * @param limit    限制数量
     * @return 最新统计数据
     */
    List<UserBehaviorStatsDO> getLatestUserBehaviorStats(Integer statType, Integer limit);

    // ========== 用户行为详情管理 ==========

    /**
     * 记录用户行为详情
     *
     * @param behaviorDetail 行为详情
     * @return 记录的行为详情
     */
    UserBehaviorDetailDO recordUserBehaviorDetail(UserBehaviorDetailDO behaviorDetail);

    /**
     * 批量记录用户行为详情
     *
     * @param behaviorDetails 行为详情列表
     * @return 是否记录成功
     */
    boolean batchRecordUserBehaviorDetail(List<UserBehaviorDetailDO> behaviorDetails);

    /**
     * 分页查询用户行为详情
     *
     * @param userId         用户ID
     * @param behaviorType   行为类型
     * @param userType       用户类型
     * @param startTime      开始时间
     * @param endTime        结束时间
     * @param sessionId      会话ID
     * @param behaviorResult 行为结果
     * @param pageNo         页码
     * @param pageSize       页大小
     * @return 分页结果
     */
    PageResult<UserBehaviorDetailDO> getUserBehaviorDetailPage(Long userId, Integer behaviorType, Integer userType,
                                                                LocalDateTime startTime, LocalDateTime endTime,
                                                                String sessionId, Integer behaviorResult,
                                                                int pageNo, int pageSize);

    /**
     * 获取用户行为详情
     *
     * @param userId    用户ID
     * @param startTime 开始时间
     * @param endTime   结束时间
     * @return 行为详情列表
     */
    List<UserBehaviorDetailDO> getUserBehaviorDetails(Long userId, LocalDateTime startTime, LocalDateTime endTime);

    /**
     * 获取用户最近行为
     *
     * @param userId 用户ID
     * @param limit  限制数量
     * @return 最近行为列表
     */
    List<UserBehaviorDetailDO> getUserRecentBehaviors(Long userId, Integer limit);

    /**
     * 获取热门功能
     *
     * @param startTime 开始时间
     * @param endTime   结束时间
     * @param limit     限制数量
     * @return 热门功能列表
     */
    List<Map<String, Object>> getPopularFeatures(LocalDateTime startTime, LocalDateTime endTime, Integer limit);

    // ========== 用户功能路径管理 ==========

    /**
     * 记录用户功能路径
     *
     * @param featurePath 功能路径
     * @return 记录的功能路径
     */
    UserFeaturePathDO recordUserFeaturePath(UserFeaturePathDO featurePath);

    /**
     * 更新用户功能路径
     *
     * @param featurePath 功能路径
     * @return 是否更新成功
     */
    boolean updateUserFeaturePath(UserFeaturePathDO featurePath);

    /**
     * 分页查询用户功能路径
     *
     * @param userId              用户ID
     * @param userType            用户类型
     * @param completionStatus    完成状态
     * @param conversionAchieved  是否达成转化
     * @param startTime           开始时间
     * @param endTime             结束时间
     * @param pageNo              页码
     * @param pageSize            页大小
     * @return 分页结果
     */
    PageResult<UserFeaturePathDO> getUserFeaturePathPage(Long userId, Integer userType, Integer completionStatus,
                                                          Boolean conversionAchieved, LocalDateTime startTime,
                                                          LocalDateTime endTime, int pageNo, int pageSize);

    /**
     * 获取用户功能路径
     *
     * @param userId    用户ID
     * @param startTime 开始时间
     * @param endTime   结束时间
     * @return 功能路径列表
     */
    List<UserFeaturePathDO> getUserFeaturePaths(Long userId, LocalDateTime startTime, LocalDateTime endTime);

    /**
     * 获取用户最近路径
     *
     * @param userId 用户ID
     * @param limit  限制数量
     * @return 最近路径列表
     */
    List<UserFeaturePathDO> getUserRecentPaths(Long userId, Integer limit);

    /**
     * 获取热门路径
     *
     * @param startTime 开始时间
     * @param endTime   结束时间
     * @param limit     限制数量
     * @return 热门路径列表
     */
    List<Map<String, Object>> getPopularPaths(LocalDateTime startTime, LocalDateTime endTime, Integer limit);

    /**
     * 获取高转化路径
     *
     * @param startTime           开始时间
     * @param endTime             结束时间
     * @param minConversionRate   最小转化率
     * @return 高转化路径列表
     */
    List<UserFeaturePathDO> getHighConversionPaths(LocalDateTime startTime, LocalDateTime endTime, 
                                                    BigDecimal minConversionRate);

    // ========== 行为数据分析 ==========

    /**
     * 分析功能使用模式
     *
     * @param startDate 开始日期
     * @param endDate   结束日期
     * @return 分析结果
     */
    Map<String, Object> analyzeFeatureUsagePattern(LocalDate startDate, LocalDate endDate);

    /**
     * 分析用户转化漏斗
     *
     * @param startDate 开始日期
     * @param endDate   结束日期
     * @return 分析结果
     */
    Map<String, Object> analyzeConversionFunnel(LocalDate startDate, LocalDate endDate);

    /**
     * 分析用户路径模式
     *
     * @param startTime 开始时间
     * @param endTime   结束时间
     * @return 分析结果
     */
    Map<String, Object> analyzeUserPathPattern(LocalDateTime startTime, LocalDateTime endTime);

    /**
     * 分析用户参与度
     *
     * @param startTime 开始时间
     * @param endTime   结束时间
     * @return 分析结果
     */
    Map<String, Object> analyzeUserEngagement(LocalDateTime startTime, LocalDateTime endTime);

    /**
     * 分析功能流失点
     *
     * @param startTime 开始时间
     * @param endTime   结束时间
     * @return 分析结果
     */
    Map<String, Object> analyzeFeatureDropOff(LocalDateTime startTime, LocalDateTime endTime);

    // ========== 数据管理 ==========

    /**
     * 删除过期的行为统计数据
     *
     * @param beforeDate 截止日期
     * @return 删除数量
     */
    int deleteExpiredBehaviorStats(LocalDate beforeDate);

    /**
     * 删除过期的行为详情数据
     *
     * @param beforeTime 截止时间
     * @return 删除数量
     */
    int deleteExpiredBehaviorDetails(LocalDateTime beforeTime);

    /**
     * 删除过期的功能路径数据
     *
     * @param beforeTime 截止时间
     * @return 删除数量
     */
    int deleteExpiredFeaturePaths(LocalDateTime beforeTime);

    /**
     * 获取计算进度
     *
     * @param startDate 开始日期
     * @param endDate   结束日期
     * @return 进度信息
     */
    Map<String, Object> getCalculationProgress(LocalDate startDate, LocalDate endDate);

    /**
     * 检查数据完整性
     *
     * @param startDate 开始日期
     * @param endDate   结束日期
     * @return 完整性检查结果
     */
    Map<String, Object> checkDataIntegrity(LocalDate startDate, LocalDate endDate);
}